<html xmlns="http://www.w3.org/1999/xhtml" id="using-components"
      xmlns:d="docbook">
<head>
  <title>Using Laszlo Components</title>
</head>

<body>

<h1>Using Laszlo Components</h1>
 
<p> 
This chapter, under construction, explains how various of the Laszlo built-in components were constructed.

</p>
<fixme>
Explain that Laszlo ships with a bunch of built-in components, which are explained in this
chapter.  <xref linkend="custom-components">A later chapter</xref> explains how to roll your own.
</fixme>

<h2>Overview</h2>

<fixme>some content here?  Otherwise remove this section.</fixme>

<h2>Button </h2>
 
 
<p>The default component button has a height of 22 pixels and a width determined
  by the length of the button text and its padding. The button face is 18 pixels
  tall with 2 pixel borders for the bezels. The type is centered on the button
  face. The button is comprised of scalable vector resources which enable disproportional
  resizing without distortion. Resizing the button does not alter the text size.
  The button can also contain an icon image with or without text included </p>
<p>The button form is constructed of four views. The views are:</p>
<ul>
<li>The "Outer Bezel" creates an indented area around the button</li>
<li>The "Inner Bezel" defines the edges of the button </li>
<li>The &quot;Simple Face&quot; is the face of the button. </li>
<li>The &quot;Text&quot; for the button label -11 pt Verity Roman</li>
  </ul>
<p> An icon or image can be used with text or alone.</p>
<p>Views 1-3 are constructed as multiple frame resources which change based on
  the state of the button. (See the <tagname link="true">state</tagname> reference page and <xref linkend="states">the chapter on
<a href="${dguide}states.html">states</a> chapter of the Developer's Guide</xref> for more about this feature of LZX.)</p>

<p>The outer and inner bezels (and each of their states) are constructed of a "hairline" .swf
  file with two different colored strokes on each rectangle. These files were
  built using the Flash authoring tool, and take advantage of a feature of the
  .swf file format that is not supported in other vector-based programs (such
  as Adobe Illustrator). Hairline strokes created in Flash will retain their
  weight regardless of scaling<d:footnote>

<d:para>An unfortunate effect of this technique is that a "hairline"
only retains its width when decreasing scale. Scaling a "hairline" up
will scale the thickness of the stroke. In an effort to work around
this, the assets for both outer and inner bezels (and their states)
are set at the overly large size of 500x500 pixels.</d:para>

</d:footnote>. This means that using a size other than the
  default will not distort the look of the button. Although transparent, the
  disabled state of the button (which is visually smaller) retains the Outer
  Bezel to insure alignment with the other resources. </p>

<p>The face view contains a .swf resource which is a vector gradient acting as
  the face of the button. There are four separate files for each of the button states,
  each with its own gradation and opacity. These files are saved as one pixel wide
  by 18 pixel high (default face height) resources and are scaled horizontally
  to the width of the button.</p>

<img src="images/image026.png" width="466" height="594"
     title="Button states and resources"/>

<example title="Buttons in context" class="code">
&lt;canvas height="550" bgcolor="0xeaeaea"&gt;
  &lt;font name="smallfont" src="verity/verity9.ttf"/&gt;
  &lt;class name="box" extends="basecomponent"
         focusable="false" height="10" width="10" /&gt;
  
  &lt;view x="40" y="40"&gt;
    &lt;view&gt;
      &lt;simplelayout axis="y" spacing="2"/&gt;
      &lt;button width="100"&gt;Cancel&lt;/button&gt;
        &lt;text&gt;button with width specified&lt;/text&gt;
    &lt;/view&gt;

    &lt;view&gt;
      &lt;simplelayout axis="y" spacing="2"/&gt;
      &lt;button height="30"&gt;Click Me&lt;/button&gt;
      &lt;text y="10"&gt;button with height specified&lt;/text&gt;
    &lt;/view&gt;

    &lt;view&gt;
      &lt;simplelayout axis="y" spacing="2"/&gt;
      &lt;button isdefault="true"&gt;Submit&lt;/button&gt;
      &lt;text&gt;default button sized to text&lt;/text&gt;
    &lt;/view&gt;

    &lt;view layout="axis:y; spacing:2"&gt;
      &lt;view layout="axis:x; spacing:40"&gt;
        &lt;button width="32" height="32"&gt;
          &lt;view resource="../icons/plane_icon.swf"  x="5" y="5"/&gt;
        &lt;/button&gt;
        &lt;button width="40" height="40" text="travel" text_y="24" font="smallfont"&gt;
          &lt;view resource="../icons/plane_icon.swf"  x="9" y="4"/&gt;
        &lt;/button&gt;
        &lt;button text_x="20" width="70" text="Search"&gt;
          &lt;view x="6" bgcolor="yellow" height="10" width="10" valign="middle"/&gt;
        &lt;/button&gt;
      &lt;/view&gt;
      &lt;text y="8"&gt;icon buttons, with and without text&lt;/text&gt;
    &lt;/view&gt;

    &lt;view&gt;
      &lt;button id="left1" style="{basecolor:0xbbffbb}" text="foo" width="100"/&gt;
      &lt;view &gt;
        &lt;simplelayout axis="x" spacing="2"/&gt;
        &lt;text&gt;button tinted this hue &lt;/text&gt;
        &lt;view height="12" width="12" y="2" bgcolor="black"&gt;
          &lt;box bgcolor="0xbbffbb" x="1" y="1"/&gt;
        &lt;/view&gt;
      &lt;/view&gt;
      &lt;button id="left2" style="{basecolor:0xbbbbff}" text="foo" width="100"/&gt;
      &lt;view&gt;
        &lt;simplelayout axis="x" spacing="2"/&gt;
        &lt;text&gt;button tinted this hue &lt;/text&gt;
        &lt;view height="12" width="12" y="2" bgcolor="black"&gt;
          &lt;box bgcolor="0xbbbbff" x="1" y="1"/&gt;
        &lt;/view&gt;
      &lt;/view&gt;
      &lt;simplelayout axis="y" spacing="10"/&gt;
    &lt;/view&gt;
    &lt;simplelayout axis="y" spacing="20"/&gt;
  &lt;/view&gt;
&lt;/canvas&gt;
</example>

<h2>Check Box </h2>
 
<p>The default <classname>checkbox</classname> has a height and width of 15 pixels. The check box is
  a scalable vector resource which enables proportional resizing without distortion.
  Disproportional scaling will result in an odd check mark.</p>

<p>All resources in check box (including disabled state) have the same exterior
  dimensions. Resources which appear to be smaller contain invisible rectangles
  that surround the visible art. This ensures the resource frames automatically
  register with one another, and will not need to be repositioned in code.</p>

<p>Check box is constructed as single resources for the various states. The placement
  of associated text has been defined to compliment the default size. Text is
  left-aligned and set to the right of the button. The disabled state, although
  visually smaller, has the same dimensions as the enabled versions. A transparent
  rectangle (indicated by white dashed line) insures alignment when a check box
  changes state.</p>

<img src="images/image032.png" width="457" height="238"
     title="Check box states and resources"/>

<example class="code" title="checkbox">
&lt;canvas width="800" height="400" bgcolor="0xeaeaea"&gt;
  &lt;bluestyle name="bluecolors" canvascolor="null"/&gt;
  &lt;greenstyle name="greencolors" canvascolor="null"/&gt;

  &lt;view x="40" y="40"&gt;
    &lt;view&gt;
      &lt;checkbox id="b" name="cb1"  value="true" text="checked by default"/&gt;
      &lt;checkbox id="c" name="cb2"  enabled="false" text="disabled"/&gt;
      &lt;checkbox id="a" name="cb3" style="bluecolors" text="a blue style checkbox"/&gt;
      &lt;checkbox id="d" name="green" style="greencolors" text="I would like to see a green square"/&gt;
      &lt;view width="40" height="40" bgcolor="green" visible="${d.value}"/&gt;
      &lt;simplelayout spacing="16"/&gt;
    &lt;/view&gt;
    &lt;view height="108" width="250" bgcolor="silver"&gt;
      &lt;view height="1" width="${parent.width}" bgcolor="0x7D7D7D"/&gt;
      &lt;checkbox x="12" id="checkMe" text="Check me" value="true"/&gt;
      &lt;view height="1" width="${parent.width}" bgcolor="0x7D7D7D"/&gt;
      &lt;view x="20"&gt;
        &lt;button height="20" text="Toggle" onclick= "checkMe.setAttribute('value', !checkMe.value);"/&gt;
        &lt;text  text="${'value:' + checkMe.value}"/&gt;
        &lt;simplelayout axis="x" spacing="6"/&gt;
      &lt;/view&gt;
      &lt;view x="20"&gt;
        &lt;button height="20" text="Disable" onclick= "checkMe.setAttribute('enabled', false);"/&gt;
        &lt;button height="20" text="Enable" onclick= "checkMe.setAttribute('enabled', true)"/&gt;
        &lt;text resize="true" text="${'enabled:' + checkMe.enabled}"/&gt;
        &lt;simplelayout axis="x" spacing="6"/&gt;
      &lt;/view&gt;
      &lt;simplelayout axis="y" spacing="10"/&gt;
    &lt;/view&gt;
    &lt;simplelayout axis="x" spacing="60"/&gt;
  &lt;/view&gt;
&lt;/canvas&gt;
</example>


<h2><a name="combobox"/>ComboBox</h2>
 <p>The <classname>combobox</classname> is defined by three pieces:</p>
<ul>
<li>The button, which activates the menu (right side)</li>
<li>The text area, containing the default menu item</li>
<li>The menu (aka floating list) </li>
</ul>
<p>The combo box contains an attribute to create either editable or non-editable
  instances of this component. The button is the same for both versions and consists
  of a multi-frame resource for the different states. The text area has a different
  look for editable and non-editable versions. The floating list is the same
  for both.</p>
<p>The default combo box has a height of 22 pixels and a width determined by
  the length of the largest content item and its padding. The type is left aligned.</p>

<img src="images/image054.png" width="190" height="180"
     title="Combo box"/>

<img src="images/image057.png" width="540" height="614"
     title="Combo box construction, states, and resources"/>

<example class="code" title="combobox">
&lt;canvas bgcolor="#EAEAEA" width="640" height="500"&gt;
  &lt;include href="lz"/&gt;
  &lt;dataset name="items"&gt;
      &lt;item value="item1" &gt;item one&lt;/item&gt;
      &lt;item value="item2" &gt;item two&lt;/item&gt;
      &lt;item value="item3" &gt;item three&lt;/item&gt;
      &lt;item value="item4" &gt;item four&lt;/item&gt;
  &lt;/dataset&gt;

  &lt;dataset name="longdata"&gt;
    &lt;date&gt;
      &lt;day&gt;1&lt;/day&gt;
      &lt;day&gt;2&lt;/day&gt;
      &lt;day&gt;3&lt;/day&gt;
      &lt;day&gt;4&lt;/day&gt;
      &lt;day&gt;5&lt;/day&gt;
      &lt;day&gt;6&lt;/day&gt;
      &lt;day&gt;7&lt;/day&gt;
      &lt;day&gt;8&lt;/day&gt;
      &lt;day&gt;9&lt;/day&gt;
      &lt;day&gt;10&lt;/day&gt;
      &lt;day&gt;11&lt;/day&gt;
      &lt;day&gt;12&lt;/day&gt;
      &lt;day&gt;13&lt;/day&gt;
      &lt;day&gt;14&lt;/day&gt;
      &lt;day&gt;15&lt;/day&gt;
      &lt;day&gt;16&lt;/day&gt;
      &lt;day&gt;17&lt;/day&gt;
      &lt;day&gt;18&lt;/day&gt;
      &lt;day&gt;19&lt;/day&gt;
      &lt;day&gt;20&lt;/day&gt;
      &lt;day&gt;21&lt;/day&gt;
      &lt;day&gt;22&lt;/day&gt;
      &lt;day&gt;23&lt;/day&gt;
      &lt;day&gt;24&lt;/day&gt;
      &lt;day&gt;25&lt;/day&gt;
      &lt;day&gt;26&lt;/day&gt;
      &lt;day&gt;27&lt;/day&gt;
      &lt;day&gt;28&lt;/day&gt;
      &lt;day&gt;29&lt;/day&gt;
      &lt;day&gt;30&lt;/day&gt;
      &lt;day&gt;31&lt;/day&gt;
    &lt;/date&gt;
  &lt;/dataset&gt;

  &lt;constantlayout axis="x" value="60"/&gt;
  &lt;simplelayout axis="y" inset="60" spacing="60"/&gt;

  &lt;view layout="axis: y; spacing :4"&gt;
    &lt;text multiline="true" width="350"&gt;The text that appears in the combobox may be different from the
    value represented by that list item&lt;/text&gt;
    &lt;view layout="axis: x; spacing :30"&gt;
      &lt;view layout="spacing:4"&gt;
        &lt;text&gt;editable combobox&lt;/text&gt;
        &lt;combobox id="cbox1"
                  width="130"
                  defaulttext="choose one..."&gt;
          &lt;textlistitem datapath="items:/item/" text="$path{'text()'}"
                        value="$path{'@value'}"/&gt;
        &lt;/combobox&gt;
        &lt;text text="${'value: ' + cbox1.value}"/&gt;
      &lt;/view&gt;
      &lt;view layout="spacing: 4"&gt;
        &lt;text&gt;non-editable combobox&lt;/text&gt;
        &lt;combobox id="cbox2"
                  width="130" editable="false"&gt;
          &lt;textlistitem datapath="items:/item/" text="$path{'text()'}"
                        value="$path{'@value'}"/&gt;
        &lt;/combobox&gt;
        &lt;text text="${'value: ' + cbox2.value}"/&gt;
      &lt;/view&gt;
    &lt;/view&gt;
  &lt;/view&gt;

  &lt;view layout="axis:x; spacing:10"&gt;
    &lt;text multiline="true" width="260"&gt;You can present a long list of
      items but specify fewer "shownitems" and the list will be displayed
      with a scrollbar.  The combobox to the right has shownitems="7"&lt;/text&gt;
    &lt;combobox y="10" width="40" editable="false"
              dataoption="lazy" shownitems="7"&gt;
      &lt;textlistitem  datapath="longdata:/date/day/text()"/&gt;
    &lt;/combobox&gt;
  &lt;/view&gt;
&lt;/canvas&gt;
</example>

<h3>Optimizing combobox startup time</h3>
<p>
If you will have more items in your list that appear to the user, you should
use dataoption="lazy".  In this case the listitem will use lazy replication and
the list will use a dataselectionmanager, instead of a selectionmanager.  Some
of the APIs for adding and removing items will not be available, but startup
time will be significantly faster.  In general, you can modifiy
data through the data APIs, instead of using list methods.  If you have created
your own listitem class you should read more about the datapath
<attribute tagname="datapath">replication</attribute> attribute.
</p>

<p>
In the example below, only four textlistitem views are created,
even though there are ten
items in the dataset.  (Note: if you declare a textlistitem with a child
datapath, you must set <code>datareplication="lazy"</code> on the datapath element
if you set <code>dataoption="lazy"</code> in the list.  If you are using a <attribute>datapath</attribute>
attribute, that happens automatically.)
</p>

<example class="code" id="combobox-4">
&lt;canvas width="200" height="140"&gt;
  &lt;dataset name="mydata"&gt;
    &lt;numbers&gt;
      &lt;option name="first"/&gt;
      &lt;option name="second"/&gt;
      &lt;option name="third"/&gt;
      &lt;option name="fourth"/&gt;
      &lt;option name="fifth"/&gt;
      &lt;option name="sixth"/&gt;
      &lt;option name="seventh"/&gt;
      &lt;option name="eigth"/&gt;
      &lt;option name="ninth"/&gt;
      &lt;option name="tenth"/&gt;
    &lt;/numbers&gt;
  &lt;/dataset&gt;
  &lt;combobox id="mycombo" shownitems="4" dataoption="lazy"&gt;
    &lt;textlistitem datapath="mydata:/numbers/option/@name"/&gt;
  &lt;/combobox&gt;
  &lt;text text="${mycombo.value}"/&gt;
  &lt;simplelayout spacing="4" inset="10"/&gt;
  &lt;constantlayout value="10" axis="x"/&gt;
&lt;/canvas&gt;
</example>


<h2><a name="edittext"></a>Editable Text Field </h2>

<p>The default edit text field, <classname>edittext</classname>, has a height of 22 pixels and a width of 106 pixels.
  The field is comprised of scalable vector resources which enable disproportional
  resizing without distortion. Resizing the edit text field will not alter the
  text.</p>

<p>Edit Text is constructed of four views:</p>
<ul>
<li>The "Outer Bezel" creates an indented area around the field</li>
<li>The "Inner Bezel" defines the recess of the field</li>
<li>The &quot;Face&quot; is the background and center of the field</li>
<li>The &quot;Text&quot; view which is contained in an input text field</li>
</ul>
<p>Each of the first three views contains multiple resource frames which change
  based on the state of the button. </p>
<p>The outer and inner bezels (and each of their states) are constructed of a "hairline" .swf
  file with two different colored strokes on each rectangle. These files were
  built using the Flash authoring tool, and take advantage of a feature of the
  .swf file format that is not supported in other vector-based programs (such
  as Illustrator). "Hairlines" created in Flash will retain their weight regardless
  of scaling. This means that using a size other than the default will not distort
  the look.</p>
<p>The face is an LZX view with a background color (bgcolor). The opacity and
bgcolor change between enabled and disabled states.</p>

<img src="images/image060.png" width="503" height="455"
     title="Editable text field states and resources"/>

<example class="code" title="Edittext">
&lt;canvas bgcolor="0xeaeaea" height="500"&gt;
  &lt;include href="lz/library.lzx" /&gt;
  &lt;dataset name="ds"&gt;
    &lt;item&gt;first item from dataset&lt;/item&gt;
    &lt;item&gt;second item from dataset&lt;/item&gt;
    &lt;item&gt;third item from a dataset&lt;/item&gt;
  &lt;/dataset&gt;
  
  &lt;view x="40" y="40" width="420" height="360" bgcolor="silver"&gt;
    &lt;constantlayout axis="x" value="20"/&gt;
    &lt;simplelayout spacing="12" inset="20"/&gt;
    &lt;edittext id="a"&gt;Name&lt;/edittext&gt;
    &lt;edittext id="b" text="Address"&gt;&lt;/edittext&gt;
    &lt;edittext id="c" text="555-555-1234"&gt;&lt;/edittext&gt;
    &lt;view&gt;
      &lt;text text="Notes:"/&gt;
      &lt;edittext id="d" text="Multiline text displayed in an inputtext box with a defined width and height."
          width="370" height="50" multiline="true"/&gt;
      &lt;simplelayout spacing="2"/&gt;
    &lt;/view&gt;
    &lt;view&gt;
      &lt;simplelayout spacing="10" axis="x"/&gt;
      &lt;text text="Username:"/&gt;
      &lt;edittext id="d1"/&gt;
      &lt;text text="Password:"/&gt;
      &lt;edittext id="d2" password="true" text="password"/&gt;
    &lt;/view&gt;
  
    &lt;view datapath="ds:/"&gt;
      &lt;constantlayout axis="x" value="15"/&gt;
      &lt;simplelayout spacing="10"/&gt;
      &lt;edittext width="150" datapath="item/text()"/&gt;
    &lt;/view&gt;
  &lt;/view&gt;
&lt;/canvas&gt;
</example>

<h2>Floating List</h2>
<p>The floating list is used in conjunction with other components. Both combobox
  and menu use this component. </p>
<p>The floating list is defined by six pieces:</p>
<ul>
<li> The end caps (constructed of 3 pieces each)</li>
<li> The menu area </li>
<li> List highlight</li>
 
<li> List selection </li>
<li>Text (icon can be used in place of text)  </li>
<li>The menu-shadow</li>
</ul>

<p>The menu, highlight and selection areas are shapes defined in LZX code and
  have no external resources. The border and background colors are attributes
  which are defined in the floating list class and styles; both can be easily
  customized. The highlight and selection are created by telling the list item
  background color to change depending on interaction.</p>

<p>The end caps are rarely used together on one floating list and are each comprised
  of three swfs: left, middle and right. The end caps are designed to scale horizontally.
  Scaling the end caps vertically is not advised. Text is 11pt Verity Roman</p>

<p>The highlight and selected rectangles have a default height of 19 pixels and
  a width determined by the width of the menu. The type is inset and left aligned
  within the menu.</p>
<p>The menu shadow is a 5 piece view<d:footnote>

<img src="images/image035.png" width="452" height="618"
     title="More info on multi-piece views"/>
</d:footnote>. The shadow middle resources stretch in
  both the direction of their orientation, and are constrained to the width and
  height of the floating list. Shadows were constructed in Macromedia Flash using &quot;Soften
  edges&quot; and a gradation of 100% black to 0% black. </p>

<p>The top right shadow resource has 3 frames that switch between states depending
  on the context and position of the menu </p>

<p>The frames are:</p>
<dl>
  <dt><code>pop_shadow_flush_top_rt.swf</code></dt>
  <dd>no top cap (combo box, menu)</dd>
  <dt><code>pop_shadow_corner_top_rt.swf</code></dt>
  <dd>no top cap (submenus)</dd>
  <dt><code>pop_shadow_oval_top_rt.swf</code></dt>
  <dd>for use with the top cap</dd>
</dl>

</body>
</html>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2001-2004 Laszlo Systems, Inc.  All Rights Reserved.              *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->
